Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
What it Is
OpenDoc defines the structures ODPoint, ODRect and ODPolygon, which are heavily used by its imaging and layout subsystems. You can read all about them in the Types & Constants section of the OpenDoc Class Reference. As defined in the official API, these are "dumb" structs, simple places to store data. There are a lot of common operations that one wants to perform on these kinds of geometric objects, and since we're (almost) all using C++ these days, it would be nice to have methods defined on those structs to perform these operations. That's what the AltPoint and AltPoly utilities do.
These utilities do not affect the data format of these structs, they just attach utility methods to them. Code that uses these utilities can freely interoperate with code that doesn't.
Build System
These utilities do their magic by defining the types ODPoint, ODRect and ODPolygon before they're normally defined in ODTypes.h. Therefore, if you're going to use them you have to include them before ODTypes.h. Like so:
#include <AltPoint.h>
#include <AltPoly.h>
#include <ODTypes.h>
Most sample parts and frameworks have already set this up for you in their precompiled headers.
Of course, you also have to compile AltPoint.cpp and/or AltPoly.cpp into your part.
ODPoint
Most of the operations on ODPoint should be clear from the header file AltPoint.h. Here are some highlights:
You can declare an ODPoint and provide initial coordinate values:
ODPoint foo( 123, 456); // first x then y
The IntX and IntY methods return the x or y coordinates as integers.
Points can be compared via the == and != operators. Also useful is the ApproxEquals method, which compares two points for near equality. This method is useful since round-off error is a fact of life in fixed-point math, and two points that should be exactly equal may in fact differ infinitesimally.
On the Macintosh, there are also some conversion operators that help in converting back and forth between ODPoints and Points. The ODPoint constructor will take a Point as a parameter — this also lets you pass a Point to a function parameter expecting an ODPoint. (The reverse conversion, from ODPoint to Point, is not implicit, to avoid accidental round-off error. It's a method called AsQDPoint.) An ODPoint can also be assigned a Point as a value, and Points can be added to / subtracted from ODPoints.
ODRect
ODRect includes most of the same convenience methods as ODPoint, including constructors, comparisons and conversion operators to/from the Mac Toolbox's "Rect" type. In addition:
An ODRect can be set from two ODPoints (defining the top-left and bottom-right corners) or from an ODPoint defining the top-left, and a width and a height value.
The operator &= intersects a rectangle with another. For example:
r1 &= r2; // intersect r1 with r2, store result in r1.
The |= operator is a union operation. You can even union a rectangle with a point, which expands it to include the point.
There are tests to see if a rectangle includes a point or completely includes another rectangle; or if it intersects a rectangle.
ODPolygon
ODPolygons are more complex than ODPoints or ODRects, since they are variable-sized structures (types of ODByteArray) that have to manage dynamic storage.
Clear disposes of the polygon's data buffer and sets it to NULL. Delete disposes the polygon's data and the ODPolygon struct itself (presumably you had allocated it on the heap.) HasData tests whether the polygon contains any data, GetDataSize returns its length, and GetData returns a pointer to the data. SetData points the data-pointer at the memory block passed in as a parameter.
GetNContours returns the number of contours. FirstContour returns a pointer to the first contour, as an ODContour*. This gives you direct access to its data. To iterate through the contours, you could then call NextContour on the contour (not on the polygon) until it returned NULL.
Most of the geometric operations (IsRectangular, Transform, etc.) should be self-evident. It's worth noting that IsEmpty is not perfect: it only tests whether the polygon contains zero contours. It's possible for the polygon to contain contours that just happen to enclose zero area, but the IsEmpty method won't consider this polygon to be empty. Watch out.
AsRectangle converts a rectangular polygon (with one contour containing four points, with edges parallel to the coordinate axes) into an ODRectangle. If the polygon is not rectangular, it returns kODFalse.
On the MacOS, HasExactRegion returns true if the polygon can be converted into a region without loss of accuracy — if it consists of horizontal and vertical edges only, with all integer coordinates. AsQDRegion converts the polygon into a QuickDraw Region, approximating if necessary. AsGXShape constructs a new QuickDraw GX polygon shape identical to the polygon.
SetNVertices resizes the data buffer to store a single contour with the given number of vertices. You can then call FirstContour to get the contour, and start jamming points into it. SetVertices does the same thing, but also sets the coordinates of the vertices from an array of ODPoints that you pass in.
SetContours creates a multi-contour polygon. You supply the number of contours, and an array of long integers giving the number of vertices of each contour. This does not set the coordinates of the vertices; you'll need to iterate through the contours to do that.
SetRect makes the polygon identical to the ODRect passed in.
ReadFrom reads polygon data from a pre-focused storage unit value. WriteTo writes to a storage unit value.
